/*
 * Copyright (C) 2007 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.android.dx.util;

/**
 * Interface for a binary output destination that may be augmented with textual
 * annotations.
 */
public interface AnnotatedOutput extends Output {

	/**
	 * Get whether this instance will actually keep annotations.
	 * 
	 * @return {@code true} iff annotations are being kept
	 */
	public boolean annotates();

	/**
	 * Get whether this instance is intended to keep verbose annotations.
	 * Annotators may use the result of calling this method to inform their
	 * annotation activity.
	 * 
	 * @return {@code true} iff annotations are to be verbose
	 */
	public boolean isVerbose();

	/**
	 * Add an annotation for the subsequent output. Any previously open
	 * annotation will be closed by this call, and the new annotation marks all
	 * subsequent output until another annotation call.
	 * 
	 * @param msg
	 *            {@code non-null;} the annotation message
	 */
	public void annotate(String msg);

	/**
	 * Add an annotation for a specified amount of subsequent output. Any
	 * previously open annotation will be closed by this call. If there is
	 * already pending annotation from one or more previous calls to this
	 * method, the new call "consumes" output after all the output covered by
	 * the previous calls.
	 * 
	 * @param amt
	 *            {@code >= 0;} the amount of output for this annotation to
	 *            cover
	 * @param msg
	 *            {@code non-null;} the annotation message
	 */
	public void annotate(int amt, String msg);

	/**
	 * End the most recent annotation. Subsequent output will be unannotated,
	 * until the next call to {@link #annotate}.
	 */
	public void endAnnotation();

	/**
	 * Get the maximum width of the annotated output. This is advisory:
	 * Implementations of this interface are encouraged to deal with too-wide
	 * output, but annotaters are encouraged to attempt to avoid exceeding the
	 * indicated width.
	 * 
	 * @return {@code >= 1;} the maximum width
	 */
	public int getAnnotationWidth();
}
